Trigger Scripting Reference
Introduction Server side Game Scripts (GS) handle the functionality of objects and clients in game. They are saved with the file extenstion ".gs" in the subfolder "standard\objects\scripts". GS are also saved in Map files, when Triggers are used. Script format Blank lines are ignored, any other line must start with a special character: # - Comment @ - Entry point ! - Instruction When the script is parsed, instructions are appended to the end of one of several linked lists. The last entry point directive determines which list the current instruction is being added to. When something in game triggers an entry point of an object, the game will step through the isntructions in that list and execute them. #text ... Ignored, just like a blank line @ frequency | max_frequency See GS Entry Points below for valid entry points. Not all entry points require a frequency (Ignored when unnecessary). ! param ... See GS Instruction Dictionary & GS Object Names below for valid commands and parameters. Valid Parameter Types include: * Text: !setstate self idle * Integer: !damageradius target 150 500 * Cvar: !push found #kickX# #kickY# #kickZ# * Statement: !if mycvar>1 @then0 GS Entry Points Important Notes: Map trigger scripts can ONLY use the entry @activate. Entries relating to Objects state (applies only to Items) @activate - Object has been activated (also: Map trigger was actived) @active - Object is in activated mode (executed for each frame) @idle - Object has been ordered to idle @idling - Object is in idle mode (executed for each frame) @sleep - Object has been ordered to sleep @sleeping - Object is in sleep mode (executed for each frame) Entries relating to Objects management (applies only to Items) @pickup - Object was picked up on Terrain @given - Object was added to inventory by command !give @drop - Object was removed from inventory by command !drop @toss - Object was removed from inventory by command !toss @attach - Object was attached to Parent by command !attach @spawn - Owner of object has spawned or was resurrected Entries relating to Usage, Weapons and Damage @use - Parent Player used item, or powerup was applied to player @fuse - Object fusetime period has expired (fusetime > 0) @backfire - Object back-fired (startFuseAtCharge 1) @fizzle - Tech Weapon fizzled because Parent has state "lockdownTech 1" @impact - Weapon or Projectile has hit something @wounded - Object took damage @die - Object took fatal damage @fire - (not working yet) @block - Object has blocked (client-only) @blocking - Object is blocking (client-only) @levelup - Object advanced a level (client-only) Entries relating to AI Objects management @walking - Object is walking towards a fixed point @chasing - Object is following another object Entries relating to GameScript logics @then0 .. @then9 - Executed by commands !if and !ifnot GS Object Names * "self" - Object that is acting * "target" - Object that initiated the action * "enemy" - Object's current enemy * "owner" - Object's owner, if any * "link" - Object's link, if any * "found" - Object found by last !search * "null" - No target (for entries like !exec) GS Instruction Dictionary Important Note: * Parameters shown between the symbols < > are REQUIRED. * Parameters shown between the symbols [ ] are optional. * The symbols ( ) mean these parameters are required only if another parameter has been specified. * The parameter can take any of the values described in the section above. Healing/Damage !heal Heal object by specified amount. If amount < 1.0, the value represents a percentage of full health. If amount >= 1.0, the value represents a fixed amount of health. !damage ignoreArmor Damage object by specified amount. If amount < 1.0, the value represents a percentage of full health. If amount >= 1.0, the value represents a fixed amount of health. If ignoreArmor = 1 (optional), the damage is not shielded by armor. !damageradius targetFlag1 targetFlag2 ... If NO flags: Damage everything in radius around object (including object itself). If flags: Damage everything flagged in radius around object (excluding object itself). Damage is inversely proportional to distance between the object and victim. List of valid flags: enemy neutral ally unit player npc item building !die Kill object. !revive Resurrect object with specified health percentage (0-1). Slots/Ammo/Stamina/Gold/Experience/States !inventory slot Checks content of player's specified inventory slot. If slot is not specified, the currently selected slot is used instead. Information is returned in Cvars: gs_inventory_name & gs_inventory_count Note1: script will error out if is not a player unit. Note2: slots are indexed from 0, so slot 1 in-game is slot 0 in-script. Example: !inventory owner 3 !exec null "chat Item in slot 3: #gs_inventory_name#" !give ammo slot Give specified object to player. (ex: human_potion) If ammo is not specified, value is 1. If slot is not specified, object is assigned to currently selected slot. Also causes the immediate execution of entry @given for that object. Note: slots are indexed from 0, so slot 1 in-game is slot 0 in-script. !remove slot Remove the item in specified slot of target player's inventory. If slot is not specified, the currently selected slot is used instead. Note1: slots are indexed from 0, so slot 1 in-game is slot 0 in-script. Note2: Does not trigger any entry points! !giveammo Give ammo for player's ranged weapons. The total amount is calculated depending on the last parameter: : Total = current + (multiplier * amount) : Total = current + (multiplier * ammoGroup) : Total = (multiplier * ammoStart) : Total = (multiplier * ammoMax) NOTE: While , and are to be written out exactly, "amount" is actually a number specificed instead. !givemana Give object the specified amount of mana. always represents a fixed amount. !givestamina Give object the specified amount of stamina. always represents a fixed amount. !givegold Give object the specified amount of gold. always represents a fixed amount. !givegoldradius If flags(for now): Grant gold to allies/enemies in radius around object (excluding object itself) and only to clients. always represents a fixed amount. Relative to the given. !giveexp Give object the specified amount of experience. always represents a fixed amount. WARNING: The server setting "sv_xp_max_gain" directly affects how high the value of exp gain will be, limiting it to the set % of the next level. !giveexpradius If flags(for now): Grant experience to allies/enemies in radius around object (excluding object itself) and only to clients. always represents a fixed amount. Relative to the given. WARNING: The server setting "sv_xp_max_gain" directly affects how high the value of exp gain will be. !regenradius targetFlag2 ... Scan radius around object looking for anything that matches the specified flags. The first object detected gets regenarated by the specified amounts. If amount < 1.0, the value represents a percentage of maximum stat value. If amount >= 1.0, the value represents a fixed amount of the stat value. Note: Flags 1st .. 4th correspond to distance from specified object List of valid flags: enemy neutral ally unit player npc item building 1st 2nd 3rd 4th !givestate maxDuration Give specified state to object. (ex: adrenaline) If maxDuration in msec is not specified, duration is equal to . Otherwise, duration is random value in the range (minDuration:maxDuration). !givestateradius maxDuration Give specified state to all valid targets around . (ex: adrenaline) If maxDuration in msec is not specified, duration is equal to . Otherwise, duration is random value in the range (minDuration:maxDuration). WARNING: does not receive the state. "Valid" target refers to the target flags specified within the ".state" file of that state. !hasstate Check whether the object has the specified state. If the object does NOT have the state, the execution of the script breaks at this point. !stateslot Checks content of player's specified state slot. Information is returned in Cvar: gs_state_name. Example: !stateslot owner 15 !exec null "chat State in slot 15: #gs_state_name#" See XR State Reference for a list of state attributes. Players Behaviour !goal Assign target group a certain goal (move, attack...) : only the object is assigned the goal. : object's team is assigned the goal. : specified team is assigned the goal. ... ... : specified team is assigned the goal. : everyone in every team is assigned the goal. <#num> : only object #num is assigned the goal (num can be 0-1024). <##cvar#>: same as above, but with object num retrieved from cvar. <$name> : only client with matching name is assigned the goal. The nature of the goal depends on the following parameter: : move to location : act on nearest object to location that object's type & team determines the goal (attack, build...) !push Pushes object along specified direction vector (strength is length of vector). This force is added on top of the current velocity of that object. !pull Pulls given object towards acting object (self). This force is added on top of the current velocity of that object. !physics Alters the physics of object. !teleport ( ) Teleport object to a new location defined by the second parameter: : teleport object to team's command centre. : teleport object to location of acting object (aka self). : if object has a linked object in inventory, teleport to that location. : teleport object to location . !stun Stun object for a set period of time. represents stun time in msec. !stunradius |targetFlag2| |targetFlag3| Stun units in radius around object corresponding to given targetFlags (excluding object itself). represents stun time in msec. List of valid flags: enemy neutral ally Items Behaviour !drop Drop object from inventory to precise location on the ground. & are relative to the player's current position and angle. The object remains "linked" to the player who dropped it (ex: see teleport). Also causes the immediate execution of entry @drop. !toss Toss object from inventory to the ground. The object remains "linked" to the player who tossed it (ex: see teleport). Also causes the immediate execution of entry @toss. !attach Allocate model, and attach it to specified object (ex: sacrifice). Also causes the immediate execution of entry @attach. !destabilize targetFlag2 ... Kills all "volatile" objects matching the flags within specified radius of object. Volatile objects have the field isvolatile=1 in their ".object" definition. List of valid flags: enemy neutral ally unit item building !scan targetFlag2 ... Scan radius around object looking for anything that matches the specified flags. When an object is detected, switches to the state . Note: Flags 1st .. 4th correspond to distance from specified object. List of valid flags: enemy neutral ally unit player npc item building 1st 2nd 3rd 4th List of valid states: sleep idle activate !search targetFlag2 ... Scan radius around object looking for anything that matches the specified flags. When an object is detected, the GS Target "found" is updated to point to it. Note: Flags 1st .. 4th correspond to distance from specified object List of valid flags: enemy neutral ally unit player npc item building 1st 2nd 3rd 4th Example: !search self 70 unit ally neutral enemy 1st !exec found "set kickX 300*gs_object_dirx" !exec found "set kickY 300*gs_object_diry" !exec found "set kickZ 100" !push found #kickX# #kickY# #kickZ# !notify found player "^rU've been Kicked in the Ass!" Events !exec client "command" Executes the console command specified between brackets on server. The optional use of "client" allows the execution to happen on client instead. Note: Script files (*.cfg) can be executed with the command: "exec script.cfg" !notify "message" Send notification in chat window to selected group of clients. : only the object receives the message. : object's team receives the message. : everyone in every team receives the message. !spawnobject () Spawns a new object at the specified location. If object is an item, its ".object" file must have "set canPickup 1". : type of object to be created (ex: npc_chiprel). : team this object will belong to (0 to 4). : behaviour towards (only valid if new object is npc). : spawn new object within melee range of . : spawn new object at location . WARNING: Do NOT under any circumstance spawn a SH/Lair (command center)! Never! !playsoundradius Plays a sound for all clients in radius around target. is the path+filename relative to the "game" folder. Example: /sound/human/buildings/construction.ogg !changeunit Transform target object (client-only) into given unit. (ex: npc_chiprel) Also causes the immediate execution of entry @spawn for that object. Note: The !exec function is very powerful, it allows: * The execution of console commands. * The modification of any cvar value. * The execution of custom scripts with the command: !exec null "exec script.cfg" For the full list of console commands see: Server Commands Logics !if Test whether the object meets the specified condition. If the condition IS met, the specified entry is executed. Note: Conditions such as ally/ennemy are relative to the acting object (aka self). List of valid conditions: enemy neutral ally character siege npc building item corpse condition can also be a statement, such as: myCvar1>=myCvar2 List of valid entries: @then0 ... @then9 Example: !if null bot_index 0 @then0 !ifnot Test whether the object meets the specified condition. If the condition IS NOT met, the specified entry is executed. Note: Conditions such as ally/ennemy are relative to the acting object (aka self). List of valid conditions: enemy neutral ally character siege npc building item corpse condition can also be a statement, such as: _myCvar1>=_myCvar2 List of valid entries: @then0 ... @then9 Example: !if null _bot_index 0 @then0 !test Test whether the object meets the specified condition. If the condition IS NOT met, the execution of the script breaks at this point. Note: Conditions such as ally/ennemy are relative to the acting object (aka self). List of valid conditions: enemy neutral ally character siege npc corpse building item !testnot param ... Test whether the object meets the specified condition. If the condition IS met, the execution of the script breaks at this point. Note: Conditions such as ally/ennemy are relative to the acting object (aka self). List of valid conditions: enemy neutral ally character siege npc corpse building item !setstate [ ] Switch object to specified . If optional in msec is specified, switch to afterwards. List of valid states: sleep idle activate !delay Allows a delay in msec before switching to the first state specified in "setstate". The "delay" command must be written AFTER the "setstate" command in the script. GS Internal Cvars Whenever a GS is executed, the engine automatically updates the content of these Cvars. These can be used as parameters to any instruction (ex: #gs_object_mana#). Object Info: Information about the specified object. * gs_object_id: Index of object (between 1 and 128 if object is a player) * gs_object_nick: Nickname of object (only valid if object is a player) * gs_object_name: Name of object (ex: human_nomad, beast_lair...) * gs_object_type: Type of object (client, npc, item, building) * gs_object_team: Team the object belongs to (0, 1, 2, 3 or 4) * gs_object_posx, gs_object_posy, gs_object_posz: Location of object * gs_object_dirx, gs_object_diry, gs_object_dirz: Orientation vector of object * gs_object_scale: Scale of object * gs_object_mana, gs_object_manapercent, gs_object_manamax: Object's mana * gs_object_health, gs_object_healthpercent, gs_object_healthmax: Object's health Parent Info: Only valid for Triggers. Information about Trigger's Parent Object. * gs_parent_id: Index of object (between 1 and 128 if object is a player) * gs_parent_posx, gs_parent_posy, gs_parent_posz: Location of object * gs_parent_dirx, gs_parent_diry, gs_parent_dirz: Orientation vector of object * gs_parent_scale: Scale of object Game Info: General Information about Game. * gs_game_time. * gs_game_status. * gs_game_status_end. * gs_team1_resource1 .. gs_team4_resource5. Transmitted Info: These variables can be modified by GS instructions. The value is then automatically transmitted to Clients. * gs_transmit1 .. gs_transmit9. For example, these variables can be used to refresh custom GUI Information. Example of Use In this example, a "psphere" Map Trigger is looking for buildings being constructed inside the sphere. When a Team completes the construction of a building, we want the Trigger to execute a GS that increments a variable telling us how many buildings that team has placed within the sphere. The following script would do the job: @activate !exec target "inc _buildings_team#gs_object_team# 1" Category:Scripting